home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 November / Freeware November 1998.img / dist / fw_tar.idb / usr / freeware / info / tar.info-3.z / tar.info-3 (.txt)
GNU Info File  |  1998-05-21  |  47KB  |  864 lines
  1. This is Info file tar.info, produced by Makeinfo version 1.67 from the
  2. input file tar.texi.
  3. START-INFO-DIR-ENTRY
  4. * tar: (tar).            Making tape (or disk) archives.
  5. END-INFO-DIR-ENTRY
  6.    This file documents GNU `tar', a utility used to store, backup, and
  7. transport files.
  8.    Copyright (C) 1992, 1994, 1995, 1996, 1997 Free Software Foundation,
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Foundation.
  20.    This file documents GNU `tar', which is a utility used to store,
  21. backup, and transport files.  `tar' is a tape (or disk) archiver.  This
  22. manual documents the release 1.12.
  23. File: tar.info,  Node: Basic tar,  Next: Advanced tar,  Prev: operations,  Up: operations
  24. Basic GNU `tar' Operations
  25. ==========================
  26.    The basic `tar' operations, `--create' (`-c'), `--list' (`-t') and
  27. `--extract' (`--get', `-x'), are currently presented and described in
  28. the tutorial chapter of this manual.  This section provides some
  29. complementary notes for these operations.
  30. `--create' (`-c')
  31.      Creating an empty archive would have some kind of elegance.  One
  32.      can initialize an empty archive and later use `--append' (`-r')
  33.      for adding all members.  Some applications would not welcome
  34.      making an exception in the way of adding the first archive member.
  35.      On the other hand, many people reported that it is dangerously
  36.      too easy for `tar' to destroy a magnetic tape with an empty
  37.      archive(1).  The two most common errors are:
  38.        1. Mistakingly using `create' instead of `extract', when the
  39.           intent was to extract the full contents of an archive.  This
  40.           error is likely: keys `c' and `x' are right next ot each
  41.           other on the QWERTY keyboard.  Instead of being unpacked, the
  42.           archive then gets wholly destroyed.  When users speak about
  43.           "exploding" an archive, they usually mean something else :-).
  44.        2. Forgetting the argument to `file', when the intent was to
  45.           create an archive with a single file in it.  This error is
  46.           likely because a tired user can easily add the `f' key to the
  47.           cluster of option letters, by the mere force of habit,
  48.           without realizing the full consequence of doing so.  The
  49.           usual consequence is that the single file, which was meant to
  50.           be saved, is rather destroyed.
  51.      So, recognizing the likelihood and the catastrophical nature of
  52.      these errors, GNU `tar' now takes some distance from elegance, and
  53.      cowardly refuses to create an archive when `--create' (`-c')
  54.      option is given, there are no arguments besides options, and
  55.      `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option is *not*
  56.      used.  To get around the cautiousness of GNU `tar' and
  57.      nevertheless create an archive with nothing in it, one may still
  58.      use, as the value for the `--files-from=FILE-OF-NAMES' (`-T
  59.      FILE-OF-NAMES') option, a file with no names in it, as shown in
  60.      the following commands:
  61.           tar --create --file=empty-archive.tar --files-from=/dev/null
  62.           tar cfT empty-archive.tar /dev/null
  63. `--extract' (`--get', `-x')
  64.      A socket is stored, within a GNU `tar' archive, as a pipe.
  65. `--list' (`-t')
  66.      GNU `tar' now shows dates as `1996-11-09', while it used to show
  67.      them as `Nov 11 1996'.  (One can revert to the old behavior by
  68.      defining `USE_OLD_CTIME' in `src/list.c' before reinstalling.) But
  69.      preferrably, people you should get used to ISO 8601 dates.  Local
  70.      American dates should be made available again with full date
  71.      localisation support, once ready.  In the meantime, programs not
  72.      being localisable for dates should prefer international dates,
  73.      that's really the way to go.
  74.      Look up `http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html' if
  75.      you are curious, it contains a detailed explanation of the ISO
  76.      8601 standard.
  77.    ---------- Footnotes ----------
  78.    (1)  This is well described in `Unix-haters Handbook', by Simson
  79. Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN
  80. 1-56884-203-1.
  81. File: tar.info,  Node: Advanced tar,  Next: extract options,  Prev: Basic tar,  Up: operations
  82. Advanced GNU `tar' Operations
  83. =============================
  84.    Now that you have learned the basics of using GNU `tar', you may
  85. want to learn about further ways in which `tar' can help you.
  86.    This chapter presents five, more advanced operations which you
  87. probably won't use on a daily basis, but which serve more specialized
  88. functions.  We also explain the different styles of options and why you
  89. might want to use one or another, or a combination of them in your `tar'
  90. commands.  Additionally, this chapter includes options which allow you
  91. to define the output from `tar' more carefully, and provide help and
  92. error correction in special circumstances.
  93. * Menu:
  94. * Operations::
  95. * current state::
  96. * append::
  97. * update::
  98. * concatenate::
  99. * delete::
  100. * compare::
  101. File: tar.info,  Node: Operations,  Next: current state,  Prev: Advanced tar,  Up: Advanced tar
  102. The Five Advanced `tar' Operations
  103. ----------------------------------
  104.      *(This message will disappear, once this node revised.)*
  105.    In the last chapter, you learned about the first three operations to
  106. `tar'.  This chapter presents the remaining five operations to `tar':
  107. `--append', `--update', `--concatenate', `--delete', and `--compare'.
  108.    You are not likely to use these operations as frequently as those
  109. covered in the last chapter; however, since they perform specialized
  110. functions, they are quite useful when you do need to use them.  We will
  111. give examples using the same directory and files that you created in
  112. the last chapter.  As you may recall, the directory is called
  113. `practice', the files are `jazz', `blues', `folk', `rock', and the two
  114. archive files you created are `collection.tar' and `music.tar'.
  115.    We will also use the archive files `afiles.tar' and `bfiles.tar'.
  116. `afiles.tar' contains the members `apple', `angst', and `aspic'.
  117. `bfiles.tar' contains the members `./birds', `baboon', and `./box'.
  118.    Unless we state otherwise, all practicing you do and examples you
  119. follow in this chapter will take place in the `practice' directory that
  120. you created in the previous chapter; see *Note prepare for examples::.
  121. (Below in this section, we will remind you of the state of the examples
  122. where the last chapter left them.)
  123.    The five operations that we will cover in this chapter are:
  124. `--append'
  125.      Add new entries to an archive that already exists.
  126. `--update'
  127.      Add more recent copies of archive members to the end of an
  128.      archive, if they exist.
  129. `--concatenate'
  130. `--catenate'
  131.      Add one or more pre-existing archives to the end of another
  132.      archive.
  133. `--delete'
  134.      Delete items from an archive (does not work on tapes).
  135. `--compare'
  136. `--diff'
  137.      Compare archive members to their counterparts in the file system.
  138. File: tar.info,  Node: current state,  Next: append,  Prev: Operations,  Up: Advanced tar
  139. The Current State of the Practice Files
  140. ---------------------------------------
  141.    Currently, the listing of the directory using `ls' is as follows:
  142. The archive file `collection.tar' looks like this:
  143.      $ tar -tvf collection.tar
  144. The archive file `music.tar' looks like this:
  145.      $ tar -tvf music.tar
  146. File: tar.info,  Node: append,  Next: update,  Prev: current state,  Up: Advanced tar
  147. How to Add Files to Existing Archives: `--append'
  148. -------------------------------------------------
  149.      *(This message will disappear, once this node revised.)*
  150.    If you want to add files to an existing archive, you don't need to
  151. create a new archive; you can use `--append' (`-r').  The archive must
  152. already exist in order to use `--append'.  (A related operation is the
  153. `--update' operation; you can use this to add newer versions of archive
  154. members to an existing archive.  To learn how to do this with
  155. `--update', *note update::..)
  156.    If you use `--append' (`-r') to add a file that has the same name as
  157. an archive member to an archive containing that archive member, then the
  158. old member is not deleted.  What does happen, however, is somewhat
  159. complex.  `tar' *allows* you to have infinite numbers of files with the
  160. same name.  Some operations treat these same-named members no
  161. differently than any other set of archive members: for example, if you
  162. view an archive with `--list' (`-t'), you will see all of those members
  163. listed, with their modification times, owners, etc.
  164.    Other operations don't deal with these members as perfectly as you
  165. might prefer; if you were to use `--extract' (`--get', `-x') to extract
  166. the archive, only the most recently added copy of a member with the
  167. same name as four other members would end up in the working directory.
  168. This is because `--extract' extracts an archive in the order the
  169. members appeared in the archive; the most recently archived members
  170. will be extracted last.  Additionally, an extracted member will
  171. *overwrite* a file of the same name which existed in the directory
  172. already, and `tar' will not prompt you about this.  Thus, only the most
  173. recently archived member will end up being extracted, as it will
  174. overwrite the one extracted before it, and so on.
  175.    There are a few ways to get around this.  .
  176.    If you want to replace an archive member, use `--delete' to delete
  177. the member you want to remove from the archive, , and then use
  178. `--append' to add the member you want to be in the archive.  Note that
  179. you can not change the order of the archive; the most recently added
  180. member will still appear last.  In this sense, you cannot truely
  181. "replace" one member with another.  (Replacing one member with another
  182. will not work on certain types of media, such as tapes; see *Note
  183. delete:: and *Note Media::, for more information.)
  184. * Menu:
  185. * appending files::             Appending Files to an Archive
  186. * multiple::
  187. File: tar.info,  Node: appending files,  Next: multiple,  Prev: append,  Up: append
  188. Appending Files to an Archive
  189. .............................
  190.      *(This message will disappear, once this node revised.)*
  191.    The simplest way to add a file to an already existing archive is the
  192. `--append' (`-r') operation, which writes specified files into the
  193. archive whether or not they are already among the archived files.  When
  194. you use `--append', you *must* specify file name arguments, as there is
  195. no default.  If you specify a file that already exists in the archive,
  196. another copy of the file will be added to the end of the archive.  As
  197. with other operations, the member names of the newly added files will
  198. be exactly the same as their names given on the command line.  The
  199. `--verbose' (`-v') option will print out the names of the files as they
  200. are written into the archive.
  201.    `--append' cannot be performed on some tape drives, unfortunately,
  202. due to deficiencies in the formats those tape drives use.  The archive
  203. must be a valid `tar' archive, or else the results of using this
  204. operation will be unpredictable.  *Note Media::.
  205.    To demonstrate using `--append' to add a file to an archive, create
  206. a file called `rock' in the `practice' directory.  Make sure you are in
  207. the `practice' directory.  Then, run the following `tar' command to add
  208. `rock' to `collection.tar':
  209.      $ tar --append --file=collection.tar rock
  210. If you now use the `--list' (`-t') operation, you will see that `rock'
  211. has been added to the archive:
  212.      $ tar --list --file=collection.tar
  213.      -rw-rw-rw- me user     28 1996-10-18 16:31 jazz
  214.      -rw-rw-rw- me user     21 1996-09-23 16:44 blues
  215.      -rw-rw-rw- me user     20 1996-09-23 16:44 folk
  216.      -rw-rw-rw- me user     20 1996-09-23 16:44 rock
  217. File: tar.info,  Node: multiple,  Prev: appending files,  Up: append
  218. Multiple Files with the Same Name
  219. .................................
  220.    You can use `--append' (`-r') to add copies of files which have been
  221. updated since the archive was created.  (However, we do not recommend
  222. doing this since there is another `tar' option called `--update'; *note
  223. update::. for more information.  We describe this use of `--append'
  224. here for the sake of completeness.)   When you extract the archive, the
  225. older version will be effectively lost.  This works because files are
  226. extracted from an archive in the order in which they were archived.
  227. Thus, when the archive is extracted, a file archived later in time will
  228. overwrite a file of the same name which was archived earlier, even
  229. though the older version of the file will remain in the archive unless
  230. you delete all versions of the file.
  231.    Supposing you change the file `blues' and then append the changed
  232. version to `collection.tar'.  As you saw above, the original `blues' is
  233. in the archive `collection.tar'.  If you change the file and append the
  234. new version of the file to the archive, there will be two copies in the
  235. archive.  When you extract the archive, the older version of the file
  236. will be extracted first, and then overwritten by the newer version when
  237. it is extracted.
  238.    You can append the new, changed copy of the file `blues' to the
  239. archive in this way:
  240.      $ tar --append --verbose --file=collection.tar blues
  241.      blues
  242. Because you specified the `--verbose' option, `tar' has printed the
  243. name of the file being appended as it was acted on.  Now list the
  244. contents of the archive:
  245.      $ tar --list --verbose --file=collection.tar
  246.      -rw-rw-rw- me user     28 1996-10-18 16:31 jazz
  247.      -rw-rw-rw- me user     21 1996-09-23 16:44 blues
  248.      -rw-rw-rw- me user     20 1996-09-23 16:44 folk
  249.      -rw-rw-rw- me user     20 1996-09-23 16:44 rock
  250.      -rw-rw-rw- me user     58 1996-10-24 18:30 blues
  251. The newest version of `blues' is now at the end of the archive (note
  252. the different creation dates and file sizes).  If you extract the
  253. archive, the older version of the file `blues' will be overwritten by
  254. the newer version.  You can confirm this by extracting the archive and
  255. running `ls' on the directory.  *Note Writing:: for more information.
  256. (*Please note:* This is the case unless you employ the `--backup'
  257. option; .)
  258. File: tar.info,  Node: update,  Next: concatenate,  Prev: append,  Up: Advanced tar
  259. Updating an Archive
  260. -------------------
  261.      *(This message will disappear, once this node revised.)*
  262.    In the previous section, you learned how to use `--append' (`-r') to
  263. add a file to an existing archive.  A related operation is `--update'
  264. (`-u').  The `--update' operation updates a `tar' archive by comparing
  265. the date of the specified archive members against the date of the file
  266. with the same name.  If the file has been modified more recently than
  267. the archive member, then the newer version of the file is added to the
  268. archive (as with `--append' (`-r')).
  269.    Unfortunately, you cannot use `--update' with magnetic tape drives.
  270. The operation will fail.
  271.    Both `--update' and `--append' work by adding to the end of the
  272. archive.  When you extract a file from the archive, only the version
  273. stored last will wind up in the file system, unless you use the
  274. `--backup' option ().
  275. * Menu:
  276. * how to update::
  277. File: tar.info,  Node: how to update,  Prev: update,  Up: update
  278. How to Update an Archive Using `--update'
  279. .........................................
  280.    You must use file name arguments with the `--update' (`-u')
  281. operation.  If you don't specify any files, `tar' won't act on any
  282. files and won't tell you that it didn't do anything (which may end up
  283. confusing you).
  284.    To see the `--update' option at work, create a new file,
  285. `classical', in your practice directory, and some extra text to the
  286. file `blues', using any text editor.  Then invoke `tar' with the
  287. `update' operation and the `--verbose' (`-v') option specified, using
  288. the names of all the files in the practice directory as file name
  289. arguments:
  290.      $ tar --update -v -f collection.tar blues folk rock classical
  291.      blues
  292.      classical
  293.      $
  294. Because we have specified verbose mode, `tar' prints out the names of
  295. the files it is working on, which in this case are the names of the
  296. files that needed to be updated.  If you run `tar --list' and look at
  297. the archive, you will see `blues' and `classical' at its end.  There
  298. will be a total of two versions of the member `blues'; the one at the
  299. end will be newer and larger, since you added text before updating it.
  300.    (The reason `tar' does not overwrite the older file when updating it
  301. is because writing to the middle of a section of tape is a difficult
  302. process.  Tapes are not designed to go backward.  *Note Media:: for more
  303. information about tapes.
  304.    `--update' (`-u') is not suitable for performing backups for two
  305. reasons: it does not change directory content entries, and it lengthens
  306. the archive every time it is used.  The GNU `tar' options intended
  307. specifically for backups are more efficient.  If you need to run
  308. backups, please consult *Note Backups::.
  309. File: tar.info,  Node: concatenate,  Next: delete,  Prev: update,  Up: Advanced tar
  310. Combining Archives with `--concatenate'
  311. ---------------------------------------
  312.    Sometimes it may be convenient to add a second archive onto the end
  313. of an archive rather than adding individual files to the archive.  To
  314. add one or more archives to the end of another archive, you should use
  315. the `--concatenate' (`--catenate', `-A') operation.
  316.    To use `--concatenate', name the archives to be concatenated on the
  317. command line.  (Nothing happens if you don't list any.)  The members,
  318. and their member names, will be copied verbatim from those archives.  If
  319. this causes multiple members to have the same name, it does not delete
  320. any members; all the members with the same name coexist.  For
  321. information on how this affects reading the archive, .
  322.    To demonstrate how `--concatenate' works, create two small archives
  323. called `bluesrock.tar' and `folkjazz.tar', using the relevant files
  324. from `practice':
  325.      $ tar -cvf bluesrock.tar blues rock
  326.      blues
  327.      classical
  328.      $ tar -cvf folkjazz.tar folk jazz
  329.      folk
  330.      jazz
  331. If you like, You can run `tar --list' to make sure the archives contain
  332. what they are supposed to:
  333.      $ tar -tvf bluesrock.tar
  334.      -rw-rw-rw- melissa user    105 1997-01-21 19:42 blues
  335.      -rw-rw-rw- melissa user     33 1997-01-20 15:34 rock
  336.      $ tar -tvf folkjazz.tar
  337.      -rw-rw-rw- melissa user     20 1996-09-23 16:44 folk
  338.      -rw-rw-rw- melissa user     65 1997-01-30 14:15 jazz
  339.    We can concatenate these two archives with `tar':
  340.      $ cd ..
  341.      $ tar --concatenate --file=bluesrock.tar jazzfolk.tar
  342.    If you now list the contents of the `bluesclass.tar', you will see
  343. that now it also contains the archive members of `jazzfolk.tar':
  344.      $ tar --list --file=bluesrock.tar
  345.      blues
  346.      rock
  347.      jazz
  348.      folk
  349.    When you use `--concatenate', the source and target archives must
  350. already exist and must have been created using compatable format
  351. parameters ().  The new, concatenated archive will be called by the
  352. same name as the first archive listed on the command line.
  353.    Like `--append' (`-r'), this operation cannot be performed on some
  354. tape drives, due to deficiencies in the formats those tape drives use.
  355.    It may seem more intuitive to you to want or try to use `cat' to
  356. concatenate two archives instead of using the `--concatenate'
  357. operation; after all, `cat' is the utility for combining files.
  358.    However, `tar' archives incorporate an end-of-file marker which must
  359. be removed if the concatenated archives are to be read properly as one
  360. archive.  `--concatenate' removes the end-of-archive marker from the
  361. target archive before each new archive is appended.  If you use `cat'
  362. to combine the archives, the result will not be a valid `tar' format
  363. archive.  If you need to retrieve files from an archive that was added
  364. to using the `cat' utility, use the `--ignore-zeros' (`-i') option.
  365. *Note Ignore Zeros:: for further information on dealing with archives
  366. improperly combined using the `cat' shell utility.
  367.    You must specify the source archives using `--file=ARCHIVE-NAME'
  368. (`-f ARCHIVE-NAME') (*note file::.).  If you do not specify the target
  369. archive, `tar' uses the value of the environment variable `TAPE', or,
  370. if this has not been set, the default archive name.
  371. File: tar.info,  Node: delete,  Next: compare,  Prev: concatenate,  Up: Advanced tar
  372. Removing Archive Members Using `--delete'
  373. -----------------------------------------
  374.      *(This message will disappear, once this node revised.)*
  375.    You can remove members from an archive by using the `--delete'
  376. option.  Specify the name of the archive with `--file=ARCHIVE-NAME'
  377. (`-f ARCHIVE-NAME') and then specify the names of the members to be
  378. deleted; if you list no member names, nothing will be deleted.  The
  379. `--verbose' (`-v') option will cause `tar' to print the names of the
  380. members as they are deleted.  As with `--extract' (`--get', `-x'), you
  381. must give the exact member names when using `tar --delete'.  `--delete'
  382. will remove all versions of the named file from the archive.  The
  383. `--delete' operation can run very slowly.
  384.    Unlike other operations, `--delete' has no short form.
  385.    This operation will rewrite the archive.  You can only use
  386. `--delete' on an archive if the archive device allows you to write to
  387. any point on the media, such as a disk; because of this, it does not
  388. work on magnetic tapes.  Do not try to delete an archive member from a
  389. magnetic tape; the action will not succeed, and you will be likely to
  390. scramble the archive and damage your tape.  There is no safe way
  391. (except by completely re-writing the archive) to delete files from most
  392. kinds of magnetic tape.  *Note Media::.
  393.    To delete all versions of the file `blues' from the archive
  394. `collection.tar' in the `practice' directory, make sure you are in that
  395. directory, and then,
  396.      $ tar --list --file=collection.tar
  397.      blues
  398.      folk
  399.      jazz
  400.      rock
  401.      practice/blues
  402.      practice/folk
  403.      practice/jazz
  404.      practice/rock
  405.      practice/blues
  406.      $ tar --delete --file=collection.tar blues
  407.      $ tar --list --file=collection.tar
  408.      folk
  409.      jazz
  410.      rock
  411.      $
  412.    The `--delete' option has been reported to work properly when `tar'
  413. acts as a filter from `stdin' to `stdout'.
  414. File: tar.info,  Node: compare,  Prev: delete,  Up: Advanced tar
  415. Comparing Archive Members with the File System
  416. ----------------------------------------------
  417.      *(This message will disappear, once this node revised.)*
  418.    The `--compare' (`-d'), or `--diff' operation compares specified
  419. archive members against files with the same names, and then reports
  420. differences in file size, mode, owner, modification date and contents.
  421. You should *only* specify archive member names, not file names.  If you
  422. do not name any members, then `tar' will compare the entire archive.
  423. If a file is represented in the archive but does not exist in the file
  424. system, `tar' reports a difference.
  425.    You have to specify the record size of the archive when modifying an
  426. archive with a non-default record size.
  427.    `tar' ignores files in the file system that do not have
  428. corresponding members in the archive.
  429.    The following example compares the archive members `rock', `blues'
  430. and `funk' in the archive `bluesrock.tar' with files of the same name
  431. in the file system.  (Note that there is no file, `funk'; `tar' will
  432. report an error message.)
  433.      $ tar --compare --file=bluesrock.tar rock blues funk
  434.      rock
  435.      blues
  436.      tar: funk not found in archive
  437. Depending on the system where you are running `tar' and the version you
  438. are running, `tar' may have a different error message, such as:
  439.      funk: does not exist
  440.    The spirit behind the `--compare' (`--diff', `-d') option is to
  441. check whether the archive represents the current state of files on
  442. disk, more than validating the integrity of the archive media.  For
  443. this later goal, *Note verify::.
  444. File: tar.info,  Node: extract options,  Next: backup,  Prev: Advanced tar,  Up: operations
  445. Options Used by `--extract'
  446. ===========================
  447.      *(This message will disappear, once this node revised.)*
  448.    The previous chapter showed how to use `--extract' (`--get', `-x')
  449. to extract an archive into the filesystem.  Various options cause `tar'
  450. to extract more information than just file contents, such as the owner,
  451. the permissions, the modification date, and so forth.  This section
  452. presents options to be used with `--extract' when certain special
  453. considerations arise.  You may review the information presented in
  454. *Note extract:: for more basic information about the `--extract'
  455. operation.
  456. * Menu:
  457. * Reading::                     Options to Help Read Archives
  458. * Writing::                     Changing How `tar' Writes Files
  459. * Scarce::                      Coping with Scarce Resources
  460. File: tar.info,  Node: Reading,  Next: Writing,  Prev: extract options,  Up: extract options
  461. Options to Help Read Archives
  462. -----------------------------
  463.      *(This message will disappear, once this node revised.)*
  464.    Normally, `tar' will request data in full record increments from an
  465. archive storage device.  If the device cannot return a full record,
  466. `tar' will report an error.  However, some devices do not always return
  467. full records, or do not require the last record of an archive to be
  468. padded out to the next record boundary.  To keep reading until you
  469. obtain a full record, or to accept an incomplete record if it contains
  470. an end-of-archive marker, specify the `--read-full-records' (`-B')
  471. option in conjunction with the `--extract' (`--get', `-x') or `--list'
  472. (`-t') operations.  *Note Blocking::.
  473.    The `--read-full-records' (`-B') option is turned on by default when
  474. `tar' reads an archive from standard input, or from a remote machine.
  475. This is because on BSD Unix systems, attempting to read a pipe returns
  476. however much happens to be in the pipe, even if it is less than was
  477. requested.  If this option were not enabled, `tar' would fail as soon
  478. as it read an incomplete record from the pipe.
  479.    If you're not sure of the blocking factor of an archive, you can
  480. read the archive by specifying `--read-full-records' (`-B') and
  481. `--blocking-factor=512-SIZE' (`-b 512-SIZE'), using a blocking factor
  482. larger than what the archive uses.  This lets you avoid having to
  483. determine the blocking factor of an archive.  *Note Blocking Factor::.
  484. * Menu:
  485. * read full records::
  486. * Ignore Zeros::
  487. * Ignore Failed Read::
  488. File: tar.info,  Node: read full records,  Next: Ignore Zeros,  Prev: Reading,  Up: Reading
  489. Reading Full Records
  490. ....................
  491. `--read-full-records'
  492.      Use in conjunction with `--extract' (`--get', `-x') to read an
  493.      archive which contains incomplete records, or one which has a
  494.      blocking factor less than the one specified.
  495. File: tar.info,  Node: Ignore Zeros,  Next: Ignore Failed Read,  Prev: read full records,  Up: Reading
  496. Ignoring Blocks of Zeros
  497. ........................
  498.    Normally, `tar' stops reading when it encounters a block of zeros
  499. between file entries (which usually indicates the end of the archive).
  500. `--ignore-zeros' (`-i') allows `tar' to completely read an archive
  501. which contains a block of zeros before the end (i.e. a damaged archive,
  502. or one which was created by `cat'-ing several archives together).
  503.    The `--ignore-zeros' (`-i') option is turned off by default because
  504. many versions of `tar' write garbage after the end-of-archive entry,
  505. since that part of the media is never supposed to be read.  GNU `tar'
  506. does not write after the end of an archive, but seeks to maintain
  507. compatablity among archiving utilities.
  508. `--ignore-zeros'
  509.      To ignore blocks of zeros (ie. end-of-archive entries) which may be
  510.      encountered while reading an archive.  Use in conjunction with
  511.      `--extract' (`--get', `-x') or `--list' (`-t').
  512. File: tar.info,  Node: Ignore Failed Read,  Prev: Ignore Zeros,  Up: Reading
  513. Ignore Fail Read
  514. ................
  515. `--ignore-failed-read'
  516.      Do not exit with nonzero on unreadable files or directories.
  517. File: tar.info,  Node: Writing,  Next: Scarce,  Prev: Reading,  Up: extract options
  518. Changing How `tar' Writes Files
  519. -------------------------------
  520.      *(This message will disappear, once this node revised.)*
  521. * Menu:
  522. * Prevention Overwriting::
  523. * Keep Old Files::
  524. * Unlink First::
  525. * Recursive Unlink::
  526. * Modification Times::
  527. * Setting Access Permissions::
  528. * Writing to Standard Output::
  529. * remove files::
  530. File: tar.info,  Node: Prevention Overwriting,  Next: Keep Old Files,  Prev: Writing,  Up: Writing
  531. Options to Prevent Overwriting Files
  532. ....................................
  533.    Normally, `tar' writes extracted files into the file system without
  534. regard to the files already on the system; i.e., files with the same
  535. names as archive members are overwritten when the archive is extracted.
  536. If the name of a corresponding file name is a symbolic link, the file
  537. pointed to by the symbolic link will be overwritten instead of the
  538. symbolic link itself (if this is possible).  Moreover, special devices,
  539. empty directories and even symbolic links are automatically removed if
  540. they are found to be on the way of the proper extraction.
  541.    To prevent `tar' from extracting an archive member from an archive
  542. if doing so will overwrite a file in the file system, use
  543. `--keep-old-files' (`-k') in conjunction with `--extract'.  When this
  544. option is specified, `tar' will report an error stating the name of the
  545. files in conflict instead of overwriting the file with the
  546. corresponding extracted archive member.
  547.    The `--unlink-first' (`-U') option removes existing files, symbolic
  548. links, empty directories, devices, etc., *prior* to extracting over
  549. them.  In particular, using this option will prevent replacing an
  550. already existing symbolic link by the name of an extracted file, since
  551. the link itself is removed prior to the extraction, rather than the
  552. file it points to.  On some systems, the backing store for the
  553. executable *is* the original program text.  You could use the
  554. `--unlink-first' (`-U') option to prevent segmentation violations or
  555. other woes when extracting arbitrary executables over currently running
  556. copies.  Note that if something goes wrong with the extraction and you
  557. *did* use this option, you might end up with no file at all.  Without
  558. this option, if something goes wrong with the extraction, the existing
  559. file is not overwritten and preserved.
  560.    If you specify the `--recursive-unlink' option, `tar' removes
  561. *anything* that keeps you from extracting a file as far as current
  562. permissions will allow it.  This could include removal of the contents
  563. of a full directory hierarchy.  For example, someone using this feature
  564. may be very surprised at the results when extracting a directory entry
  565. from the archive.  This option can be dangerous; be very aware of what
  566. you are doing if you choose to use it.
  567. * Menu:
  568. * Keep Old Files::
  569. * Unlink First::
  570. * Recursive Unlink::
  571. File: tar.info,  Node: Keep Old Files,  Next: Unlink First,  Prev: Prevention Overwriting,  Up: Writing
  572. Keep Old Files
  573. ..............
  574. `--keep-old-files'
  575.      Do not overwrite existing files from archive.  The
  576.      `--keep-old-files' (`-k') option prevents `tar' from over-writing
  577.      existing files with files with the same name from the archive.
  578.      The `--keep-old-files' (`-k') option is meaningless with `--list'
  579.      (`-t').  Prevents `tar' from overwriting files in the file system
  580.      during extraction.
  581. File: tar.info,  Node: Unlink First,  Next: Recursive Unlink,  Prev: Keep Old Files,  Up: Writing
  582. Unlink First
  583. ............
  584. `--unlink-first'
  585.      Try removing files before extracting over them, instead of trying
  586.      to overwrite them.
  587. File: tar.info,  Node: Recursive Unlink,  Next: Modification Times,  Prev: Unlink First,  Up: Writing
  588. Recursive Unlink
  589. ................
  590. `--recursive-unlink'
  591.      When this option is specified, try removing files and directory
  592.      hierarchies before extracting over them.  *This is a dangerous
  593.      option!*
  594.    Some people argue that GNU `tar' should not hesitate to overwrite
  595. files with other files when extracting.  When extracting a `tar'
  596. archive, they expect to see a faithful copy of the state of the
  597. filesystem when the archive was created.  It is debatable that this
  598. would always be a proper behaviour.  For example, suppose one has an
  599. archive in which `usr/local' is a link to `usr/local2'.  Since then,
  600. maybe the site removed the link and renamed the whole hierarchy from
  601. `/usr/local2' to `/usr/local'.  Such things happen all the time.  I
  602. guess it would not be welcome at all that GNU `tar' removes the whole
  603. hierarchy just to make room for the link to be reinstated (unless it
  604. *also* simultaneously restores the full `/usr/local2', of course!  GNU
  605. `tar' is indeed able to remove a whole hierarchy to reestablish a
  606. symbolic link, for example, but *only if* `--recursive-unlink' is
  607. specified to allow this behaviour.  In any case, single files are
  608. silently removed.
  609. File: tar.info,  Node: Modification Times,  Next: Setting Access Permissions,  Prev: Recursive Unlink,  Up: Writing
  610. Setting Modification Times
  611. ..........................
  612.    Normally, `tar' sets the modification times of extracted files to
  613. the modification times recorded for the files in the archive, but
  614. limits the permissions of extracted files by the current `umask'
  615. setting.
  616.    To set the modification times of extracted files to the time when
  617. the files were extracted, use the `--touch' (`-m') option in
  618. conjunction with `--extract' (`--get', `-x').
  619. `--touch'
  620.      Sets the modification time of extracted archive members to the time
  621.      they were extracted, not the time recorded for them in the archive.
  622.      Use in conjunction with `--extract' (`--get', `-x').
  623. File: tar.info,  Node: Setting Access Permissions,  Next: Writing to Standard Output,  Prev: Modification Times,  Up: Writing
  624. Setting Access Permissions
  625. ..........................
  626.    To set the modes (access permissions) of extracted files to those
  627. recorded for those files in the archive, use `--same-persmissions' in
  628. conjunction with the `--extract' (`--get', `-x') operation.
  629. `--preserve-permission'
  630. `--same-permission'
  631. `--ignore-umask'
  632.      Set modes of extracted archive members to those recorded in the
  633.      archive, instead of current umask settings.  Use in conjunction
  634.      with `--extract' (`--get', `-x').
  635. File: tar.info,  Node: Writing to Standard Output,  Next: remove files,  Prev: Setting Access Permissions,  Up: Writing
  636. Writing to Standard Output
  637. ..........................
  638.    To write the extracted files to the standard output, instead of
  639. creating the files on the file system, use `--to-stdout' (`-O') in
  640. conjunction with `--extract' (`--get', `-x').  This option is useful if
  641. you are extracting files to send them through a pipe, and do not need to
  642. preserve them in the file system.  If you extract multiple members,
  643. they appear on standard output concatenated, in the order they are
  644. found in the archive.
  645. `--to-stdout'
  646.      Writes files to the standard output.  Used in conjunction with
  647.      `--extract' (`--get', `-x').  Extract files to standard output.
  648.      When this option is used, instead of creating the files specified,
  649.      `tar' writes the contents of the files extracted to its standard
  650.      output.  This may be useful if you are only extracting the files
  651.      in order to send them through a pipe.  This option is meaningless
  652.      with `--list' (`-t').
  653. File: tar.info,  Node: remove files,  Prev: Writing to Standard Output,  Up: Writing
  654. Removing Files
  655. ..............
  656. `--remove-files'
  657.      Remove files after adding them to the archive.
  658. File: tar.info,  Node: Scarce,  Prev: Writing,  Up: extract options
  659. Coping with Scarce Resources
  660. ----------------------------
  661.      *(This message will disappear, once this node revised.)*
  662. * Menu:
  663. * Starting File::
  664. * Same Order::
  665. File: tar.info,  Node: Starting File,  Next: Same Order,  Prev: Scarce,  Up: Scarce
  666. Starting File
  667. .............
  668. `--starting-file=NAME'
  669. `-K NAME'
  670.      Starts an operation in the middle of an archive.  Use in
  671.      conjunction with `--extract' (`--get', `-x') or `--list' (`-t').
  672.    If a previous attempt to extract files failed due to lack of disk
  673. space, you can use `--starting-file=NAME' (`-K NAME') to start
  674. extracting only after member NAME of the archive.  This assumes, of
  675. course, that there is now free space, or that you are now extracting
  676. into a different file system.  (You could also choose to suspend `tar',
  677. remove unnecessary files from the file system, and then restart the
  678. same `tar' operation.  In this case, `--starting-file=NAME' (`-K NAME')
  679. is not necessary.  *Note Inc Dumps::, *Note interactive::, and
  680. *Note exclude::.)
  681. File: tar.info,  Node: Same Order,  Prev: Starting File,  Up: Scarce
  682. Same Order
  683. ..........
  684. `--same-order'
  685. `--preserve-order'
  686.      To process large lists of file names on machines with small
  687.      amounts of memory.  Use in conjunction with `--compare' (`--diff',
  688.      `-d'), `--list' (`-t') or `--extract' (`--get', `-x').
  689.    The `--same-order' (`--preserve-order', `-s') option tells `tar'
  690. that the list of file names to be listed or extracted is sorted in the
  691. same order as the files in the archive.  This allows a large list of
  692. names to be used, even on a small machine that would not otherwise be
  693. able to hold all the names in memory at the same time.  Such a sorted
  694. list can easily be created by running `tar -t' on the archive and
  695. editing its output.
  696.    This option is probably never needed on modern computer systems.
  697. File: tar.info,  Node: backup,  Next: Applications,  Prev: extract options,  Up: operations
  698. Backup options
  699. ==============
  700.    GNU `tar' offers options for making backups of files before writing
  701. new versions.  These options control the details of these backups.
  702. They may apply to the archive itself before it is created or rewritten,
  703. as well as individual extracted members.  Other GNU programs (`cp',
  704. `install', `ln', and `mv', for example) offer similar options.
  705.    Backup options may prove unexpectedly useful when extracting archives
  706. containing many members having identical name, or when extracting
  707. archives on systems having file name limitations, making different
  708. members appear has having similar names through the side-effect of name
  709. truncation.  (This is true only if we have a good scheme for truncated
  710. backup names, which I'm not sure at all: I suspect work is needed in
  711. this area.) When any existing file is backed up before being
  712. overwritten by extraction, then clashing files are automatically be
  713. renamed to be unique, and the true name is kept for only the last file
  714. of a series of clashing files.  By using verbose mode, users may track
  715. exactly what happens.
  716.    At the detail level, some decisions are still experimental, and may
  717. change in the future, we are waiting comments from our users.  So,
  718. please do not learn to depend blindly on the details of the backup
  719. features.  For example, currently, directories themselves are never
  720. renamed through using these options, so, extracting a file over a
  721. directory still has good chances to fail.  Also, backup options apply
  722. to created archives, not only to extracted members.  For created
  723. archives, backups will not be attempted when the archive is a block or
  724. character device, or when it refers to a remote file.
  725.    For the sake of simplicity and efficiency, backups are made by
  726. renaming old files prior to creation or extraction, and not by copying.
  727. The original name is restored if the file creation fails.  If a
  728. failure occurs after a partial extraction of a file, both the backup
  729. and the partially extracted file are kept.
  730. `--backup'
  731.      Make backups of files that are about to be overwritten or removed.
  732.      Without this option, the original versions are destroyed.
  733. `--suffix=SUFFIX'
  734.      Append SUFFIX to each backup file made with `-b'.  If this option
  735.      is not specified, the value of the `SIMPLE_BACKUP_SUFFIX'
  736.      environment variable is used.  And if `SIMPLE_BACKUP_SUFFIX' is not
  737.      set, the default is `~', just as in Emacs.
  738. `--version-control=METHOD'
  739.      Use METHOD to determine the type of backups made with `--backup'.
  740.      If this option is not specified, the value of the `VERSION_CONTROL'
  741.      environment variable is used.  And if `VERSION_CONTROL' is not set,
  742.      the default backup type is `existing'.
  743.      This option corresponds to the Emacs variable `version-control';
  744.      the same values for METHOD are accepted as in Emacs.  This options
  745.      also more descriptive name.  The valid METHODs (unique
  746.      abbreviations are accepted):
  747.     `t'
  748.     `numbered'
  749.           Always make numbered backups.
  750.     `nil'
  751.     `existing'
  752.           Make numbered backups of files that already have them, simple
  753.           backups of the others.
  754.     `never'
  755.     `simple'
  756.           Always make simple backups.
  757.    Some people express the desire to *always* use the OP-BACKUP option,
  758. by defining some kind of alias or script.  This is not as easy as one
  759. may thing, due to the fact old style options should appear first and
  760. consume arguments a bit inpredictably for an alias or script.  But, if
  761. you are ready to give up using old style options, you may resort to
  762. using something like (a Bourne shell function here):
  763.      tar () { /usr/local/bin/tar --backup $*; }
  764. File: tar.info,  Node: Applications,  Next: looking ahead,  Prev: backup,  Up: operations
  765. Notable `tar' Usages
  766. ====================
  767.      *(This message will disappear, once this node revised.)*
  768.    You can easily use archive files to transport a group of files from
  769. one system to another: put all relevant files into an archive on one
  770. computer system, transfer the archive to another system, and extract
  771. the contents there.  The basic transfer medium might be magnetic tape,
  772. Internet FTP, or even electronic mail (though you must encode the
  773. archive with `uuencode' in order to transport it properly by mail).
  774. Both machines do not have to use the same operating system, as long as
  775. they both support the `tar' program.
  776.    For example, here is how you might copy a directory's contents from
  777. one disk to another, while preserving the dates, modes, owners and
  778. link-structure of all the files therein.  In this case, the transfer
  779. medium is a "pipe", which is one a Unix redirection mechanism:
  780.      $ cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)
  781. The command also works using short option forms:
  782.      $ cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)
  783. This is one of the easiest methods to transfer a `tar' archive.
  784. File: tar.info,  Node: looking ahead,  Prev: Applications,  Up: operations
  785. Looking Ahead: The Rest of this Manual
  786. ======================================
  787.    You have now seen how to use all eight of the operations available to
  788. `tar', and a number of the possible options.  The next chapter explains
  789. how to choose and change file and archive names, how to use files to
  790. store names of other files which you can then call as arguments to
  791. `tar' (this can help you save time if you expect to archive the same
  792. list of files a number of times), and how to
  793.    If there are too many files to conveniently list on the command line,
  794. you can list the names in a file, and `tar' will read that file.
  795. *Note files::.
  796.    There are various ways of causing `tar' to skip over some files, and
  797. not archive them.  *Note Choosing::.
  798. File: tar.info,  Node: Backups,  Next: Choosing,  Prev: operations,  Up: Top
  799. Performing Backups and Restoring Files
  800. **************************************
  801.      *(This message will disappear, once this node revised.)*
  802.    GNU `tar' is distributed along with the scripts which the Free
  803. Software Foundation uses for performing backups.  There is no
  804. corresponding scripts available yet for doing restoration of files.
  805. Even if there is a good chance those scripts may be satisfying to you,
  806. they are not the only scripts or methods available for doing backups
  807. and restore.  You may well create your own, or use more sophisticated
  808. packages dedicated to that purpose.
  809.    Some users are enthusiastic about `Amanda' (The Advanced Maryland
  810. Automatic Network Disk Archiver), a backup system developed by James da
  811. Silva `jds@cs.umd.edu' and available on many Unix systems.  This is
  812. free software, and it is available at these places:
  813.      http://www.cs.umd.edu/projects/amanda/amanda.html
  814.      ftp://ftp.cs.umd.edu/pub/amanda
  815.    Here is a possible plan for a future documentation about the
  816. backuping scripts which are provided within the GNU `tar' distribution.
  817.      .* dumps
  818.      . + what are dumps
  819.      
  820.      . + different levels of dumps
  821.      .  - full dump = dump everything
  822.      .  - level 1, level 2 dumps etc, -
  823.          A level n dump dumps everything changed since the last level
  824.          n-1 dump (?)
  825.      
  826.      . + how to use scripts for dumps  (ie, the concept)
  827.      .  - scripts to run after editing backup specs (details)
  828.      
  829.      . + Backup Specs, what is it.
  830.      .  - how to customize
  831.      .  - actual text of script  [/sp/dump/backup-specs]
  832.      
  833.      . + Problems
  834.      .  - rsh doesn't work
  835.      .  - rtape isn't installed
  836.      .  - (others?)
  837.      
  838.      . + the --incremental option of tar
  839.      
  840.      . + tapes
  841.      .  - write protection
  842.      .  - types of media
  843.      .   : different sizes and types, useful for different things
  844.      .  - files and tape marks
  845.           one tape mark between files, two at end.
  846.      .  - positioning the tape
  847.           MT writes two at end of write,
  848.             backspaces over one when writing again.
  849.    This chapter documents both the provided FSF scripts and `tar'
  850. options which are more specific to usage as a backup tool.
  851.    To "back up" a file system means to create archives that contain all
  852. the files in that file system.  Those archives can then be used to
  853. restore any or all of those files (for instance if a disk crashes or a
  854. file is accidently deleted).  File system "backups" are also called
  855. "dumps".
  856. * Menu:
  857. * Full Dumps::                  Using `tar' to Perform Full Dumps
  858. * Inc Dumps::                   Using `tar' to Perform Incremental Dumps
  859. * incremental and listed-incremental::  The Incremental Options
  860. * Backup Levels::               Levels of Backups
  861. * Backup Parameters::           Setting Parameters for Backups and Restoration
  862. * Scripted Backups::            Using the Backup Scripts
  863. * Scripted Restoration::        Using the Restore Script
  864.